Maps a character key with the Command key to determine the keyboard equivalent of a menu item in a menu in the current menu list.

SInt32 MenuKey (
    CharParameter ch
);

ch

The 1-byte character that represents the key pressed by the user in combination with the Command key.

function result

function result Returns a value containing the menu ID and menu item that corresponds to the given character.

If the given character does not map to an enabled menu item in the current menu list, MenuKey returns 0 in its high-order word and the low-order word is undefined.

If the given character maps to a menu item in a menu that a driver (such as a desk accessory) has inserted into your application’s menu list, MenuKey uses the function SystemMenu to process this occurrence and returns 0 to your application in the high-order word.

DISCUSSION

When the Appearance Manager is available, call MenuEvent instead of MenuKey, in order to map the keyboard equivalent character in the event structure to its corresponding menu and menu item. Unlike MenuKey, the MenuEvent function supports the Shift, Option, and Control modifier keys in addition to the Command key.

The MenuKey function determines whether the key combination maps to a current menu item when the user presses another key while holding down the Command key. Note that in most cases you should use the function MenuEvent since MenuEvent supports the Shift, Option, and Control modifier keys in addition to the Command key.

MenuKey does not distinguish between uppercase and lowercase letters. This allows a user to invoke a keyboard equivalent command, such as the Copy command, by pressing the Command key and “c” or “C”. For consistency between applications, you should define the keyboard equivalents of your commands so that they appear in uppercase in your menus.

You should not define menu items with identical keyboard equivalents. The MenuKey function scans the menus from right to left and the items from top to bottom. If you have defined more than one menu item with identical keyboard equivalents, MenuKey returns the first one it finds.

If the given character maps to an enabled menu item in the current menu list, MenuKey highlights the menu title of the chosen menu, returns the menu ID in the high-order word of its function result, and returns the chosen menu item in the low-order word of its function result. After performing the chosen task, your application should unhighlight the menu title using the HiliteMenu function .

The MenuKey function first searches the regular portion of the current menu list for a menu item with a keyboard equivalent matching the given key. If it doesn’t find one there, it searches the submenu portion of the current menu list. If the given key maps to a menu item in a submenu, MenuKey highlights the menu title in the menu bar that the user would normally pull down to begin traversing to the submenu. Your application should perform the desired command and then unhighlight the menu title.

You shouldn’t assign a Command–Shift–number key sequence to a menu item as its keyboard equivalent; Command–Shift–number key sequences are reserved for use as 'FKEY' resources. Command–Shift–number key sequences are not returned to your application, but instead are processed by the Event Manager. The Event Manager invokes the 'FKEY' resource with a resource ID that corresponds to the number that activates it.

Apple reserves the Command-key codes 0x1B through 0x20 to indicate meanings other than keyboard equivalents. MenuKey ignores these character codes and returns a function result of 0 if you specify any of these values in the ch parameter. Your application should not use these character codes for its own use

VERSION NOTES

This function is not recommended with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.

© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)